sec(enterprise): SECURITY.md + auth-leak fix + telemetry opt-out + stable Flask key - #40

…able Flask key

Bundle of four enterprise-readiness improvements from an independent
security review against NAB (APRA / CPS 234) and Coles (PCI-DSS / ISO
27001) procurement requirements.

E-2: Add .github/SECURITY.md (P0 compliance blocker)
================================================================
Vendor security assessments (SIG / CAIQ) ask "do you have a documented
vulnerability disclosure process?" — answer was no. Now we have:
  - Two private disclosure channels (GitHub Security Advisories + email)
  - Acknowledgement / triage / fix-plan / disclosure timeline
  - Severity-based patch SLA (Critical: 7d, High: 14d, Medium: 30d)
  - Scope boundaries (in/out of scope)
  - Supply-chain controls summary for procurement reviewers
  - Pointer to docs/enterprise.md § known limits for the trade-offs
    we've deliberately accepted

E-4: Remove /api/app-state from auth-exempt list (P1)
================================================================
app.py:808 — /api/app-state was in the same exempt list as /health.
Unauthenticated callers could fetch app_owner email + last_rotation_iso
+ owner_resolved_at, which is enough to fingerprint session timing and
identify the workspace owner.

The endpoint has no pre-auth use case in the UI (the polling endpoints
the UI needs before PAT setup are /api/setup-status and /api/pat-status,
both still exempt). Removed from the list.

Tests:
  - test_app_state_denied_for_non_owner — non-owners get 403
  - test_app_state_allowed_for_owner — owner still gets 200

E-9: Telemetry opt-out via CODA_TELEMETRY_DISABLED (P2)
================================================================
telemetry.py — log_telemetry() now short-circuits when
CODA_TELEMETRY_DISABLED is truthy. Default behaviour unchanged (telemetry
still on by default).

Why this matters for procurement: regulated customers (banks, retailers
with PCI-DSS) must inventory every outbound data flow from their
workspace boundary. CoDA's User-Agent-header telemetry to Databricks
servers was previously undisclosed and unsuppressible. Opt-out gives
those customers a clean answer for their third-party-risk register.

app.yaml gets a commented `CODA_TELEMETRY_DISABLED: "true"` example so
operators see the knob. 5 new unit tests cover truthy/falsy parsing and
that the background thread does NOT spawn when disabled.

E-11: Stable Flask secret_key via FLASK_SECRET_KEY (P2)
================================================================
app.py:56 used to be `app.secret_key = os.urandom(24)` — regenerated on
every worker restart, invalidating all Flask session cookies. With
single-worker config today this is mostly cosmetic (sessions get torn
down anyway when PTYs die with the worker), but it's a flagged finding
in any key-management audit and would actively break sessions if we
ever scaled to multi-worker.

Now reads FLASK_SECRET_KEY from env (typically wired to a Databricks
secret in app.yaml). Falls back to os.urandom for local dev with a
WARNING log line so operators see when production is using an ephemeral
key. app.yaml gets a commented example.

Test results
================================================================
- 244/244 unit tests pass
- 42/42 in the auth-enforcement + telemetry-opt-out + app-state suites
- Default behaviour unchanged when no new env vars are set

Out of scope (separate PRs / future work)
================================================================
- SBOM generation in the release workflow — PR #41
- Rate limiting on /api/configure-pat (E-3) — needs slowapi wire-up
- Session-level command audit trail (E-8) — medium effort, structured logs
- CSRF protection on /api/input (E-14) — medium effort
- `requests = git+https://...` PyPI proxy bypass (E-6) — blocked by
  Databricks internal PyPI proxy availability

Co-authored-by: Isaac

…t-status, app-state, /health)

Closes the three P3/P4 info-disclosure findings from the 2026-05-17
pen test:

1. /api/setup-status was auth-exempt and returned the full setup_state
   dict including step error messages (stderr trimmed to 500 chars). If a
   setup script failed with leaky stderr — paths, version strings, env-var
   echoes — anyone hitting the URL could read it.

2. /api/pat-status was auth-exempt and returned workspace_host. Already
   known to anyone who reached the URL (they're auth'd to the same
   workspace), but principle-of-least-info says trim it.

3. /api/app-state was auth-exempt and returned app_owner email + last
   PAT rotation timestamp. PR #40 also removes this — including the same
   one-line fix here lets it ship sooner; PR #40 will rebase cleanly.

4. /health was auth-exempt and returned version, active_sessions,
   setup_status, session_timeout_seconds. Version exposure enables
   CVE-targeted exploit selection. Trimmed to {"status": "healthy"} —
   no internal or external caller needs the rich shape (the frontend
   doesn't poll /health; the Apps platform uses its own liveness
   mechanism upstream of the app).

Removed setup-status, pat-status, and app-state from the
before_request auth-exempt list. The frontend continues to poll all
three because it loads from / (auth'd), so it already has SSO cookies.

Test changes:
- 5 new tests in TestInfoDisclosureEndpoints covering: setup-status
  denied/allowed, pat-status denied, app-state denied, /health
  minimal-response anti-leak (explicit assertions that version,
  setup_status, active_sessions are NOT in the response).
- Updated test_session_linger.py: the 24h timeout assertion now reads
  SESSION_TIMEOUT_SECONDS from the module directly instead of via
  /health, since exposing the value to unauth callers was the leak
  we're closing. Stronger test, smaller attack surface.

236/236 unit tests pass.

Co-authored-by: Isaac

Updates the requirements on [pytest-playwright](https://github.com/microsoft/playwright-pytest) to permit the latest version.
- [Release notes](https://github.com/microsoft/playwright-pytest/releases)
- [Commits](microsoft/playwright-pytest@v0.5.0...v0.8.0)

---
updated-dependencies:
- dependency-name: pytest-playwright
  dependency-version: 0.8.0
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [click](https://github.com/pallets/click) from 8.3.3 to 8.4.1.
- [Release notes](https://github.com/pallets/click/releases)
- [Changelog](https://github.com/pallets/click/blob/main/CHANGES.md)
- [Commits](pallets/click@8.3.3...8.4.1)

---
updated-dependencies:
- dependency-name: click
  dependency-version: 8.4.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [idna](https://github.com/kjd/idna) from 3.16 to 3.17.
- [Release notes](https://github.com/kjd/idna/releases)
- [Changelog](https://github.com/kjd/idna/blob/master/HISTORY.md)
- [Commits](kjd/idna@v3.16...v3.17)

---
updated-dependencies:
- dependency-name: idna
  dependency-version: '3.17'
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [pydantic-core](https://github.com/pydantic/pydantic) from 2.46.4 to 2.47.0.
- [Release notes](https://github.com/pydantic/pydantic/releases)
- [Changelog](https://github.com/pydantic/pydantic/blob/main/HISTORY.md)
- [Commits](https://github.com/pydantic/pydantic/commits)

---
updated-dependencies:
- dependency-name: pydantic-core
  dependency-version: 2.47.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Add a README section explaining the Omnigent host integration merged in #92:
what it does, how to turn it on (with the app.yaml.lakemeter overlay), the
two-credential model (SP-OAuth host tunnel + AI-Gateway harness LLM), the
runtime control endpoints, and the ENABLE_SP_APIKEYHELPER pairing. Also add
the OMNIGENTS_* / ENABLE_SP_APIKEYHELPER rows to the env-var reference table.

The feature shipped in #92 with no user-facing docs (README had zero Omnigent
mentions); this closes that gap.

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 6.2.0 to 7.0.0.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](actions/setup-python@a309ff8...5fda3b9)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-version: 7.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [softprops/action-gh-release](https://github.com/softprops/action-gh-release) from 3.0.0 to 3.0.2.
- [Release notes](https://github.com/softprops/action-gh-release/releases)
- [Changelog](https://github.com/softprops/action-gh-release/blob/master/CHANGELOG.md)
- [Commits](softprops/action-gh-release@b430933...3d0d988)

---
updated-dependencies:
- dependency-name: softprops/action-gh-release
  dependency-version: 3.0.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [actions/checkout](https://github.com/actions/checkout) from 7.0.0 to 7.0.1.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@9c091bb...3d3c42e)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: 7.0.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Bumps [astral-sh/setup-uv](https://github.com/astral-sh/setup-uv) from 8.1.0 to 9.0.0.
- [Release notes](https://github.com/astral-sh/setup-uv/releases)
- [Commits](astral-sh/setup-uv@0880764...c771a70)

---
updated-dependencies:
- dependency-name: astral-sh/setup-uv
  dependency-version: 9.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

`pytest_collection_modifyitems` in tests/e2e/conftest.py receives the
whole session's item list, not just this directory's. When the e2e
prerequisites were missing (no recorded auth.json, or the databricks CLI
not authed for the profile) it marked *every* collected test as skipped
— so `uv run pytest tests/` reported "465 skipped" and the CI Tests
workflow was passing vacuously.

Filter to items that actually live under tests/e2e/. The unit suite now
runs: 459 passed, 1 skipped.

# Conflicts:
#	README.md

# Conflicts:
#	docs/auth-and-identity.md

Conflict in _update_claude: keep main's `changed` flag + OTEL-token refresh,
route the write through _atomic_write_text, and surface failures as warnings.

Two gaps fixed while integrating against current main:

- os.replace() installs the tmp file's inode, so the atomic rewrite also
  installed the tmp file's umask-default permissions — widening
  ~/.hermes/config.yaml from the 0600 setup_hermes.py sets back to 0644 on
  every rotation. Copy the target's mode onto the tmp file first.
- _update_pi() landed on main after this PR was opened and still used a bare
  open(path, 'w') with a silent except. Give it the same existence guard,
  atomic write, and observable warning as its siblings.

New tests cover both, plus a 'quiet when nothing is installed' guard so the
new warnings can't become boot noise.

…rlay

Apps overlays *replace* app.yaml rather than merging with it, and every
setup script reads its toggle as `os.environ.get("ENABLE_<CLI>", "true")`.
So a toggle omitted from an overlay is not a no-op — it silently re-enables
that CLI's install on the deployed container.

app.yaml and app.yaml.workshop listed all five; app.yaml.template and
app.yaml.lakemeter listed only ENABLE_HERMES and ENABLE_PI, so deploys from
those overlays would install Codex and Gemini even though neither has a
compatible gateway endpoint — wasted boot time plus agents that fail on
first request.

Adds tests/test_app_yaml_overlays.py to hold the invariant: every tracked
app.yaml* declares all five toggles, values stay quoted strings (unquoted
`true` parses as a bool, which the scripts' .strip().lower() would choke on),
and a new ENABLE_* appearing in setup_*.py fails the test until it's added
to the overlays.

This is the part of #30 that main hadn't already absorbed: the toggle
mechanism itself landed separately, and main's default-on policy for
Hermes/OpenCode is a deliberate later workshop decision.

Two conflicts in app.py, both resolved by keeping *both* properties rather
than picking a side:

1. before_request exempt list — main added /api/inject-pat after this PR was
   opened. It stays exempt: it's gated on the CODA_BOOTSTRAP_SECRET shared
   secret and 404s when unset, and provisioning scripts have no SSO session.
   /api/setup-status, /api/pat-status and /api/app-state come off the list as
   this PR intends.

2. /health — this PR trimmed the body to {"status": "healthy"}; main had since
   taught it to report "degraded" when PAT rotation dies, which is how a zombie
   app becomes observable. Trimming would have deleted that signal, keeping
   main's version would have kept the leak. Now the response is audience-based:
   unauthenticated callers get only {"status": ...} (so 'degraded' still
   surfaces to a probe), and the owner gets the full diagnostic payload.

The PR's unauth /health test asserted against local-dev behaviour, where
check_authorization() fails open and would have returned the full payload.
Rewrote it to mock _is_databricks_apps so it exercises the real boundary, and
added owner-sees-detail and degraded-still-visible cases.

README's endpoint table said /health exposes session count; updated it and
marked the three newly owner-gated endpoints.

…s, app-state, /health

app.py / app.yaml conflicted with work that landed on main since this PR
was opened; resolved as follows.

before_request exempt list: this PR removed only /api/app-state, while #44
(merged just before this) removed /api/setup-status and /api/pat-status too and
documented why /api/inject-pat stays exempt. Kept #44's stronger version — it's
a superset. This PR's app-state regression tests still pass against it.

FLASK_SECRET_KEY: re-applied on top of main, and pulled the resolution out of
module-level code into _resolve_secret_key() so it's unit-testable. Added tests
for the configured path, stability across calls, whitespace-only value treated
as unset (an env var wired to an empty secret must not become the signing key),
and the random-fallback-plus-warning path. The original PR shipped this
untested.

app.yaml: kept main's env block and re-added this PR's two documented knobs
(FLASK_SECRET_KEY, CODA_TELEMETRY_DISABLED) as their own commented section
above the enterprise-mode section.

Also, for a public repo: dropped named customers from the telemetry test
docstring, corrected .github/SECURITY.md's Hermes-pin reference to the
enterprise_config location it moved to, and cross-linked .github/SECURITY.md
(how to report) with docs/SECURITY.md (how to verify a release) so the two
files don't read as duplicates.